<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Dojo View Helpers - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.dojo.view.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.dojo.view.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.dojo.data.html">Zend_Dojo_Data: dojo.data Envelopes</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.dojo.html">Zend_Dojo</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.dojo.form.html">Dojo Form Elements and Decorators</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.dojo.view" class="section"><div class="info"><h1 class="title">Dojo View Helpers</h1></div>
    

    <p class="para">
        Zend Framework provides the following Dojo-specific view helpers:
    </p>

    <ul class="itemizedlist">
        <li class="listitem">
            <p class="para">
                <em class="emphasis"> <span class="methodname">dojo()</span>:</em> setup the Dojo environment
                for your page, including dojo configuration values, custom module paths, module
                require statements, theme stylesheets, <acronym class="acronym">CDN</acronym> usage, and more.
            </p>
        </li>
    </ul>

    <div class="example" id="zend.dojo.view.setup"><div class="info"><p><b>Example #1 Using Dojo View Helpers</b></p></div>
        

        <div class="example-contents"><p>
            To use Dojo view helpers, you will need to tell your view object
            where to find them. You can do this by calling
             <span class="methodname">addHelperPath()</span>:
        </p></div>

        <pre class="programlisting brush: php">
$view-&gt;addHelperPath(&#039;Zend/Dojo/View/Helper/&#039;, &#039;Zend_Dojo_View_Helper&#039;);
</pre>


        <div class="example-contents"><p>
            Alternately, you can use <span class="classname">Zend_Dojo</span>&#039;s
             <span class="methodname">enableView()</span> method to do the work for you:
        </p></div>

        <pre class="programlisting brush: php">
Zend_Dojo::enableView($view);
</pre>

    </div>

    <div class="section" id="zend.dojo.view.dojo"><div class="info"><h1 class="title">dojo() View Helper</h1></div>
    

    <p class="para">
        The  <span class="methodname">dojo()</span> view helper is intended to simplify setting up
        the Dojo environment, including the following responsibilities:
    </p>

    <ul class="itemizedlist">
        <li class="listitem">
            <p class="para">
                Specifying either a <acronym class="acronym">CDN</acronym> or a local path to a Dojo install.
            </p>
        </li>

        <li class="listitem"><p class="para">Specifying paths to custom Dojo modules.</p></li>
        <li class="listitem"><p class="para">Specifying <strong class="command">dojo.require</strong> statements.</p></li>
        <li class="listitem"><p class="para">Specifying dijit stylesheet themes to use.</p></li>

        <li class="listitem">
            <p class="para">Specifying <strong class="command">dojo.addOnLoad()</strong> events.</p>
        </li>
    </ul>

    <p class="para">
        The  <span class="methodname">dojo()</span> view helper implementation is an example of a
        placeholder implementation. The data set in it persists between view
        objects and may be directly echoed from your layout script.
    </p>

    <div class="example" id="zend.dojo.view.dojo.usage"><div class="info"><p><b>Example #2 dojo() View Helper Usage Example</b></p></div>
        

        <div class="example-contents"><p>
            For this example, let&#039;s assume the developer will be using Dojo from
            a local path, will require several dijits, and will be
            utilizing the Tundra dijit theme.
        </p></div>

        <div class="example-contents"><p>
            On many pages, the developer may not utilize Dojo at all. So, we
            will first focus on a view script where Dojo is needed and then on the
            layout script, where we will setup some of the Dojo environment and
            then render it.
        </p></div>

        <div class="example-contents"><p>
            First, we need to tell our view object to use the Dojo view helper
            paths. This can be done in your bootstrap or an early-running
            plugin; simply grab your view object and execute the following:
        </p></div>

        <pre class="programlisting brush: php">
$view-&gt;addHelperPath(&#039;Zend/Dojo/View/Helper/&#039;, &#039;Zend_Dojo_View_Helper&#039;);
</pre>


        <div class="example-contents"><p>
            Next, the view script. In this case, we&#039;re going to specify
            that we will be using a FilteringSelect -- which will consume a
            custom store based on QueryReadStore, which we&#039;ll call
            &#039;PairedStore&#039; and store in our &#039;custom&#039; module.
        </p></div>

        <pre class="programlisting brush: php">
&lt;?php // setup data store for FilteringSelect ?&gt;
&lt;div dojoType=&quot;custom.PairedStore&quot; jsId=&quot;stateStore&quot;
    url=&quot;/data/autocomplete/type/state/format/ajax&quot;
    requestMethod=&quot;get&quot;&gt;&lt;/div&gt;

&lt;?php // Input element: ?&gt;
State: &lt;input id=&quot;state&quot; dojoType=&quot;dijit.form.FilteringSelect&quot;
    store=&quot;stateStore&quot; pageSize=&quot;5&quot; /&gt;

&lt;?php // setup required dojo elements:
$this-&gt;dojo()-&gt;enable()
             -&gt;setDjConfigOption(&#039;parseOnLoad&#039;, true)
             -&gt;registerModulePath(&#039;custom&#039;, &#039;../custom/&#039;)
             -&gt;requireModule(&#039;dijit.form.FilteringSelect&#039;)
             -&gt;requireModule(&#039;custom.PairedStore&#039;); ?&gt;
</pre>


        <div class="example-contents"><p>
            In our layout script, we&#039;ll then check to see if Dojo is enabled,
            and, if so, we&#039;ll do some more general configuration and assemble
            it:
        </p></div>

        <pre class="programlisting brush: php">
&lt;?php echo $this-&gt;doctype() ?&gt;
&lt;html&gt;
&lt;head&gt;
    &lt;?php echo $this-&gt;headTitle() ?&gt;
    &lt;?php echo $this-&gt;headMeta() ?&gt;
    &lt;?php echo $this-&gt;headLink() ?&gt;
    &lt;?php echo $this-&gt;headStyle() ?&gt;
&lt;?php if ($this-&gt;dojo()-&gt;isEnabled()){
    $this-&gt;dojo()-&gt;setLocalPath(&#039;/js/dojo/dojo.js&#039;)
                 -&gt;addStyleSheetModule(&#039;dijit.themes.tundra&#039;);
    echo $this-&gt;dojo();
   }
?&gt;
    &lt;?php echo $this-&gt;headScript() ?&gt;
&lt;/head&gt;
&lt;body class=&quot;tundra&quot;&gt;
    &lt;?php echo $this-&gt;layout()-&gt;content ?&gt;
    &lt;?php echo $this-&gt;inlineScript() ?&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>


        <div class="example-contents"><p>
            At this point, you only need to ensure that your files are in the
            correct locations and that you&#039;ve created the end point action for
            your FilteringSelect!
        </p></div>
    </div>

    <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>UTF-8 encoding used by default</b><br /></span>
        

        <p class="para">
            By default, Zend Framework uses <acronym class="acronym">UTF-8</acronym> as its default encoding, and,
            specific to this case, <span class="classname">Zend_View</span> does as well. Character encoding
            can be set differently on the view object itself using the
             <span class="methodname">setEncoding()</span> method (or the <span class="property">encoding</span>
            instantiation parameter). However, since <span class="classname">Zend_View_Interface</span> does
            not define accessors for encoding, it&#039;s possible that if you are using a custom view
            implementation with the Dojo view helper, you will not have a
             <span class="methodname">getEncoding()</span> method, which is what the view helper uses
            internally for determining the character set in which to encode.
        </p>

        <p class="para">
            If you do not want to utilize <acronym class="acronym">UTF-8</acronym> in such a situation, you will
            need to implement a  <span class="methodname">getEncoding()</span> method in your custom view
            implementation.
        </p>
    </p></blockquote>

    <div class="section" id="zend.dojo.view.dojo.declarative"><div class="info"><h1 class="title">Programmatic and Declarative Usage of Dojo</h1></div>
        

        <p class="para">
            Dojo allows both <em class="emphasis">declarative</em> and
            <em class="emphasis">programmatic</em> usage of many of its features.
            <em class="emphasis">Declarative</em> usage uses standard <acronym class="acronym">HTML</acronym> elements
            with non-standard attributes that are parsed when the page is
            loaded. While this is a powerful and simple syntax to utilize, for
            many developers this can cause issues with page validation.
        </p>

        <p class="para">
            <em class="emphasis">Programmatic</em> usage allows the developer to
            decorate existing elements by pulling them by ID or <acronym class="acronym">CSS</acronym> selectors
            and passing them to the appropriate object constructors in Dojo.
            Because no non-standard <acronym class="acronym">HTML</acronym> attributes are used, pages continue to
            validate.
        </p>

        <p class="para">
            In practice, both use cases allow for graceful degradation when
            javascript is disabled or the various Dojo script resources are
            unreachable. To promote standards and document validation,
            Zend Framework uses programmatic usage by default; the various view
            helpers will generate javascript and push it to the
             <span class="methodname">dojo()</span> view helper for inclusion when rendered.
        </p>

        <p class="para">
            Developers using this technique may also wish to explore the option
            of writing their own programmatic decoration of the page. One
            benefit would be the ability to specify handlers for dijit events.
        </p>

        <p class="para">
            To allow this, as well as the ability to use declarative syntax,
            there are a number of static methods available to set this behavior
            globally.
        </p>

        <div class="example" id="zend.dojo.view.dojo.declarative.usage"><div class="info"><p><b>Example #3 Specifying Declarative and Programmatic Dojo Usage</b></p></div>
            

            <div class="example-contents"><p>
                To specify declarative usage, simply call the static
                 <span class="methodname">setUseDeclarative()</span> method:
            </p></div>

            <pre class="programlisting brush: php">
Zend_Dojo_View_Helper_Dojo::setUseDeclarative();
</pre>


            <div class="example-contents"><p>
                If you decide instead to use programmatic usage, call the static
                 <span class="methodname">setUseProgrammatic()</span> method:
            </p></div>

            <pre class="programlisting brush: php">
Zend_Dojo_View_Helper_Dojo::setUseProgrammatic();
</pre>


            <div class="example-contents"><p>
                Finally, if you want to create your own programmatic rules, you
                should specify programmatic usage, but pass in the value &#039;-1&#039;;
                in this situation, no javascript for decorating any dijits used
                will be created.
            </p></div>

            <pre class="programlisting brush: php">
Zend_Dojo_View_Helper_Dojo::setUseProgrammatic(-1);
</pre>

        </div>
    </div>

    <div class="section" id="zend.dojo.view.dojo.themes"><div class="info"><h1 class="title">Themes</h1></div>
        

        <p class="para">
            Dojo allows the creation of themes for its dijits (widgets). You may
            select one by passing in a module path:
        </p>

        <pre class="programlisting brush: php">
$view-&gt;dojo()-&gt;addStylesheetModule(&#039;dijit.themes.tundra&#039;);
</pre>


        <p class="para">
            The module path is discovered by using the character &#039;.&#039; as a
            directory separator and using the last value in the list as the name
            of the <acronym class="acronym">CSS</acronym> file in that theme directory to use; in the example
            above, Dojo will look for the theme in
            &#039;<var class="filename">dijit/themes/tundra/tundra.css</var>&#039;.
        </p>

        <p class="para">
            When using a theme, it is important to remember to pass the theme
            class to, at the least, a container surrounding any dijits you are
            using; the most common use case is to pass it in the body:
        </p>

        <pre class="programlisting brush: html">
&lt;body class=&quot;tundra&quot;&gt;
</pre>

    </div>

    <div class="section" id="zend.dojo.view.dojo.layers"><div class="info"><h1 class="title">Using Layers (Custom Builds)</h1></div>
        

        <p class="para">
            By default, when you use a <strong class="command">dojo.require</strong> statement, dojo will make a
            request back to the server to grab the appropriate javascript file.
            If you have many dijits in place, this results in many requests to
            the server -- which is not optimal.
        </p>

        <p class="para">
            Dojo&#039;s answer to this is to provide the ability to create
            <em class="emphasis">custom builds</em>. Builds do several things:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    Groups required files into <em class="emphasis">layers</em>; a layer
                    lumps all required files into a single JS file. (Hence the name
                    of this section.)
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    &quot;Interns&quot; non-javascript files used by dijits (typically,
                    template files). These are also grouped in the same JS file as
                    the layer.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    Passes the file through ShrinkSafe, which strips whitespace and
                    comments, as well as shortens variable names.
                </p>
            </li>
        </ul>

        <p class="para">
            Some files can not be layered, but the build process will create a
            special release directory with the layer file and all other files.
            This allows you to have a slimmed-down distribution customized for
            your site or application needs.
        </p>

        <p class="para">
            To use a layer, the  <span class="methodname">dojo()</span> view helper has a
             <span class="methodname">addLayer()</span> method for adding paths to required layers:
        </p>

        <pre class="programlisting brush: html">
$view-&gt;dojo()-&gt;addLayer(&#039;/js/foo/foo.js&#039;);
</pre>


        <p class="para">
            For more information on creating custom builds, please <a href="http://dojotoolkit.org/reference-guide/dojo/index.html#package-system" class="link external">&raquo; refer
                to the Dojo build documentation</a>.
        </p>
    </div>

    <div class="section" id="zend.dojo.view.dojo.methods"><div class="info"><h1 class="title">Methods Available</h1></div>
        

        <p class="para">
            The  <span class="methodname">dojo()</span> view helper always returns an instance of
            the dojo placeholder container. That container object has the
            following methods available:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                     <span class="methodname">setView(Zend_View_Interface $view)</span>: set a view instance
                    in the container.
                </p>
            </li>

            <li class="listitem">
                <p class="para"> <span class="methodname">enable()</span>: explicitly enable Dojo integration.</p>
            </li>

            <li class="listitem">
                <p class="para"> <span class="methodname">disable()</span>: disable Dojo integration.</p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">isEnabled()</span>: determine whether or not Dojo integration
                    is enabled.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">requireModule($module)</span>: setup a
                    <strong class="command">dojo.require</strong> statement.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getModules()</span>: determine what modules have been
                    required.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">registerModulePath($module, $path)</span>:
                    register a custom Dojo module path.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getModulePaths()</span>: get list of registered module paths.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">addLayer($path)</span>: add a layer (custom build) path to
                    use.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getLayers()</span>: get a list of all registered layer paths
                    (custom builds).
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">removeLayer($path)</span>: remove the layer
                    that matches <var class="varname">$path</var> from the list of registered
                    layers (custom builds).
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">setCdnBase($url)</span>: set the base <acronym class="acronym">URL</acronym>
                    for a <acronym class="acronym">CDN</acronym>; typically, one of the
                    <b><tt>Zend_Dojo::CDN_BASE_AOL</tt></b> or
                    <b><tt>Zend_Dojo::CDN_BASE_GOOGLE</tt></b>, but it only needs
                    to be the <acronym class="acronym">URL</acronym> string prior to the version number.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getCdnBase()</span>: retrieve the base <acronym class="acronym">CDN</acronym>
                    url to utilize.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">setCdnVersion($version = null)</span>: set
                    which version of Dojo to utilize from the <acronym class="acronym">CDN</acronym>.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getCdnVersion()</span>: retrieve what
                    version of Dojo from the <acronym class="acronym">CDN</acronym> will be used.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">setCdnDojoPath($path)</span>: set the relative
                    path to the <var class="filename">dojo.js</var> or <var class="filename">dojo.xd.js</var>
                    file on a <acronym class="acronym">CDN</acronym>; typically, one of the
                    <b><tt>Zend_Dojo::CDN_DOJO_PATH_AOL</tt></b> or
                    <b><tt>Zend_Dojo::CDN_DOJO_PATH_GOOGLE</tt></b>, but it only
                    needs to be the path string following the version number.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getCdnDojoPath()</span>: retrieve the last path segment of the
                    <acronym class="acronym">CDN</acronym> url pointing to the <var class="filename">dojo.js</var> file.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">useCdn()</span>: tell the container to
                    utilize the <acronym class="acronym">CDN</acronym>; implicitly enables integration.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">setLocalPath($path)</span>: tell the container
                    the path to a local Dojo install (should be a path relative
                    to the server, and contain the <var class="filename">dojo.js</var> file itself);
                    implicitly enables integration.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getLocalPath()</span>: determine what local
                    path to Dojo is being used.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">useLocalPath()</span>: is the integration
                    utilizing a Dojo local path?
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">setDjConfig(array $config)</span>: set
                    dojo or dijit configuration values (expects assoc array).
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">setDjConfigOption($option, $value)</span>: set
                    a single dojo or dijit configuration value.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getDjConfig()</span>: get all dojo or dijit configuration
                    values.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getDjConfigOption($option, $default = null)</span>: get a
                    single dojo or dijit configuration value.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">addStylesheetModule($module)</span>: add a
                    stylesheet based on a module theme.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getStylesheetModules()</span>: get stylesheets
                    registered as module themes.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">addStylesheet($path)</span>: add a local
                    stylesheet for use with Dojo.
                </p>
            </li>

            <li class="listitem">
                <p class="para"> <span class="methodname">getStylesheets()</span>: get local Dojo stylesheets.</p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">addOnLoad($spec, $function = null)</span>: add
                    a lambda for <strong class="command">dojo.onLoad</strong> to call. If one argument is passed,
                    it is assumed to be either a function name or a javascript
                    closure. If two arguments are passed, the first is assumed
                    to be the name of an object instance variable and the second
                    either a method name in that object or a closure to utilize
                    with that object.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">prependOnLoad($spec, $function = null)</span>:
                    exactly like  <span class="methodname">addOnLoad()</span>, excepts prepends to
                    beginning of onLoad stack.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">getOnLoadActions()</span>: retrieve all
                    <strong class="command">dojo.onLoad</strong> actions registered with the container. This will
                    be an array of arrays.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">onLoadCaptureStart($obj = null)</span>:
                    capture data to be used as a lambda for <strong class="command">dojo.onLoad()</strong>.
                    If <var class="varname">$obj</var> is provided, the captured JS code will be considered
                    a closure to use with that Javascript object.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">onLoadCaptureEnd($obj = null)</span>: finish
                    capturing data for use with <strong class="command">dojo.onLoad()</strong>.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">javascriptCaptureStart()</span>:
                    capture arbitrary javascript to be included with Dojo JS
                    (onLoad, require, etc. statements).
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">javascriptCaptureEnd()</span>: finish capturing javascript.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">__toString()</span>: cast the container to a
                    string; renders all <acronym class="acronym">HTML</acronym> style and script elements.
                </p>
            </li>
        </ul>
    </div>
</div>
    <div class="section" id="zend.dojo.view.dijit"><div class="info"><h1 class="title">Dijit-Specific View Helpers</h1></div>
    

    <p class="para">
        From the Dojo manual: &quot;Dijit is a widget system layered on top of
        dojo.&quot; Dijit includes a variety of layout and form widgets designed to
        provide accessibility features, localization, and standardized (and
        themeable) look-and-feel.
    </p>

    <p class="para">
        Zend Framework ships a variety of view helpers that allow you to render
        and utilize dijits within your view scripts. There are three basic
        types:
    </p>

    <ul class="itemizedlist">
        <li class="listitem">
            <p class="para">
                <em class="emphasis">Layout Containers</em>: these are designed to be
                used within your view scripts or consumed by form decorators
                for forms, sub forms, and display groups. They wrap the various
                classes offerred in <strong class="command">dijit.layout</strong>. Each dijit layout view helper
                expects the following arguments:
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                        <var class="varname">$id</var>: the container name or <acronym class="acronym">DOM</acronym> ID.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <var class="varname">$content</var>: the content to wrap in the
                        layout container.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <var class="varname">$params</var> (optional): dijit-specific
                        parameters. Basically, any non-HTML attribute that can
                        be used to configure the dijit layout container.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <var class="varname">$attribs</var> (optional): any additional
                        <acronym class="acronym">HTML</acronym> attributes that should be used to render the
                        container div. If the key &#039;id&#039; is passed in this array, it will
                        be used for the form element <acronym class="acronym">DOM</acronym> id, and
                        <var class="varname">$id</var> will be used for its name.
                    </p>
                </li>
            </ul>

            <p class="para">
                If you pass no arguments to a dijit layout view helper, the
                helper itself will be returned. This allows you to capture
                content, which is often an easier way to pass content to the
                layout container. Examples of this functionality will be shown
                later in this section.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <em class="emphasis">Form Dijit</em>: the <strong class="command">dijit.form.Form</strong> dijit, while
                not completely necessary for use with dijit form elements, will
                ensure that if an attempt is made to submit a form that does
                not validate against client-side validations, submission will
                be halted and validation error messages raised. The form dijit
                view helper expects the following arguments:
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                        <var class="varname">$id</var>: the container name or <acronym class="acronym">DOM</acronym> ID.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <var class="varname">$attribs</var> (optional): any additional
                        <acronym class="acronym">HTML</acronym> attributes that should be used to render the
                        container div.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <var class="varname">$content</var> (optional): the content to wrap
                        in the form. If none is passed, an empty string will be
                        used.
                    </p>
                </li>
            </ul>

            <p class="para">
                The argument order varies from the other dijits in order to
                keep compatibility with the standard  <span class="methodname">form()</span> view
                helper.
            </p>
        </li>

        <li class="listitem">
            <p class="para">
                <em class="emphasis">Form Elements</em>: these are designed to be
                consumed with <span class="classname">Zend_Form</span>, but can be used
                standalone within view scripts as well. Each dijit element view
                helper expects the following arguments:
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                        <var class="varname">$id</var>: the element name or <acronym class="acronym">DOM</acronym> ID.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <var class="varname">$value</var> (optional): the current value of the element.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <var class="varname">$params</var> (optional): dijit-specific
                        parameters. Basically, any non-HTML attribute that can
                        be used to configure a dijit.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <var class="varname">$attribs</var> (optional): any additional
                        <acronym class="acronym">HTML</acronym> attributes that should be used to render the dijit.
                        If the key &#039;id&#039; is passed in this array, it will be used
                        for the form element <acronym class="acronym">DOM</acronym> id, and <var class="varname">$id</var>
                        will be used for its name.
                    </p>
                </li>
            </ul>

            <p class="para">
                Some elements require more arguments; these will be noted with
                the individual element helper descriptions.
            </p>
        </li>
    </ul>

    <p class="para">
        In order to utilize these view helpers, you need to register the path
        to the dojo view helpers with your view object.
    </p>

    <div class="example" id="zend.dojo.view.dijit.prefixpath"><div class="info"><p><b>Example #4 Registering the Dojo View Helper Prefix Path</b></p></div>
        

        <pre class="programlisting brush: php">
$view-&gt;addHelperPath(&#039;Zend/Dojo/View/Helper&#039;, &#039;Zend_Dojo_View_Helper&#039;);
</pre>

    </div>

    <div class="section" id="zend.dojo.view.dijit.layout"><div class="info"><h1 class="title">Dijit Layout Elements</h1></div>
        

        <p class="para">
            The <strong class="command">dijit.layout</strong> family of elements are for creating custom,
            predictable layouts for your site. For any questions on general
            usage, <a href="http://dojotoolkit.org/reference-guide/dijit/layout.html" class="link external">&raquo; read
            more about them in the Dojo manual</a>.
        </p>

        <p class="para">
            All dijit layout elements have the signature <strong class="command">string ($id = null, $content = &#039;&#039;,
                array $params = array(), array $attribs = array())</strong>.
            In all caess, if you pass no arguments, the helper object itself will be returned. This
            gives you access to the  <span class="methodname">captureStart()</span> and
             <span class="methodname">captureEnd()</span> methods, which allow you to capture
            content instead of passing it to the layout container.
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    <em class="emphasis">AccordionContainer</em>:
                    <strong class="command">dijit.layout.AccordionContainer</strong>. Stack all panes together
                    vertically; clicking on a pane titlebar will expand and
                    display that particular pane.
                </p>

                <pre class="programlisting brush: php">
&lt;?php echo $view-&gt;accordionContainer(
    &#039;foo&#039;,
    $content,
    array(
        &#039;duration&#039; =&gt; 200,
    ),
    array(
        &#039;style&#039; =&gt; &#039;width: 200px; height: 300px;&#039;,
    ),
); ?&gt;
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">AccordionPane</em>:
                    <strong class="command">dijit.layout.AccordionPane</strong>. For use within
                    AccordionContainer.
                </p>

                <pre class="programlisting brush: php">
&lt;?php echo $view-&gt;accordionPane(
    &#039;foo&#039;,
    $content,
    array(
        &#039;title&#039; =&gt; &#039;Pane Title&#039;,
    ),
    array(
        &#039;style&#039; =&gt; &#039;background-color: lightgray;&#039;,
    ),
); ?&gt;
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">BorderContainer</em>:
                    <strong class="command">dijit.layout.BorderContainer</strong>. Achieve layouts with
                    optionally resizable panes such as you might see in a
                    traditional application.
                </p>

                <pre class="programlisting brush: php">
&lt;?php echo $view-&gt;borderContainer(
    &#039;foo&#039;,
    $content,
    array(
        &#039;design&#039; =&gt; &#039;headline&#039;,
    ),
    array(
        &#039;style&#039; =&gt; &#039;width: 100%; height: 100%&#039;,
    ),
); ?&gt;
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">ContentPane</em>: <strong class="command">dijit.layout.ContentPane</strong>.
                    Use inside any container except AccordionContainer.
                </p>

                <pre class="programlisting brush: php">
&lt;?php echo $view-&gt;contentPane(
    &#039;foo&#039;,
    $content,
    array(
        &#039;title&#039;  =&gt; &#039;Pane Title&#039;,
        &#039;region&#039; =&gt; &#039;left&#039;,
    ),
    array(
        &#039;style&#039; =&gt; &#039;width: 120px; background-color: lightgray;&#039;,
    ),
); ?&gt;
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">SplitContainer</em>:
                    <strong class="command">dijit.layout.SplitContainer</strong>. Allows resizable content
                    panes; deprecated in Dojo in favor of BorderContainer.
                </p>

                <pre class="programlisting brush: php">
&lt;?php echo $view-&gt;splitContainer(
    &#039;foo&#039;,
    $content,
    array(
        &#039;orientation&#039;  =&gt; &#039;horizontal&#039;,
        &#039;sizerWidth&#039;   =&gt; 7,
        &#039;activeSizing&#039; =&gt; true,
    ),
    array(
        &#039;style&#039; =&gt; &#039;width: 400px; height: 500px;&#039;,
    ),
); ?&gt;
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">StackContainer</em>:
                    <strong class="command">dijit.layout.StackContainer</strong>. All panes within a
                    StackContainer are placed in a stack; build buttons or
                    functionality to reveal one at a time.
                </p>

                <pre class="programlisting brush: php">
&lt;?php echo $view-&gt;stackContainer(
    &#039;foo&#039;,
    $content,
    array(),
    array(
        &#039;style&#039; =&gt; &#039;width: 400px; height: 500px; border: 1px;&#039;,
    ),
); ?&gt;
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">TabContainer</em>:
                    <strong class="command">dijit.layout.TabContainer</strong>. All panes within a
                    TabContainer are placed in a stack, with tabs positioned on
                    one side for switching between them.
                </p>

                <pre class="programlisting brush: php">
&lt;?php echo $view-&gt;tabContainer(
    &#039;foo&#039;,
    $content,
    array(),
    array(
        &#039;style&#039; =&gt; &#039;width: 400px; height: 500px; border: 1px;&#039;,
    ),
); ?&gt;
</pre>

            </li>
        </ul>

        <p class="para">
            The following capture methods are available for all layout
            containers:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    <strong class="command">captureStart($id, array $params = array(), array $attribs =
                        array());</strong>: begin capturing content to include in a container.
                    <var class="varname">$params</var> refers to the dijit params to use with
                    the container, while <var class="varname">$attribs</var> refer to any
                    general <acronym class="acronym">HTML</acronym> attributes to use.
                </p>

                <p class="para">
                    Containers may be nested when capturing, <em class="emphasis">so long
                    as no ids are duplicated</em>.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">captureEnd($id)</span>:
                    finish capturing content to include in a container.
                    <var class="varname">$id</var> should refer to an id previously used with
                    a  <span class="methodname">captureStart()</span> call. Returns a string
                    representing the container and its contents, just as if
                    you&#039;d simply passed content to the helper itself.
                </p>
            </li>
        </ul>

        <div class="example" id="zend.dojo.view.dijit.layout.borderexample"><div class="info"><p><b>Example #5 BorderContainer layout dijit example</b></p></div>
            

            <div class="example-contents"><p>
                BorderContainers, particularly when coupled with the ability to
                capture content, are especially useful for achieving complex
                layout effects.
            </p></div>

            <pre class="programlisting brush: php">
$view-&gt;borderContainer()-&gt;captureStart(&#039;masterLayout&#039;,
                                       array(&#039;design&#039; =&gt; &#039;headline&#039;));

echo $view-&gt;contentPane(
    &#039;menuPane&#039;,
    &#039;This is the menu pane&#039;,
    array(&#039;region&#039; =&gt; &#039;top&#039;),
    array(&#039;style&#039; =&gt; &#039;background-color: darkblue;&#039;)
);

echo  $view-&gt;contentPane(
    &#039;navPane&#039;,
    &#039;This is the navigation pane&#039;,
    array(&#039;region&#039; =&gt; &#039;left&#039;),
    array(&#039;style&#039; =&gt; &#039;width: 200px; background-color: lightblue;&#039;)
);

echo $view-&gt;contentPane(
    &#039;mainPane&#039;,
    &#039;This is the main content pane area&#039;,
    array(&#039;region&#039; =&gt; &#039;center&#039;),
    array(&#039;style&#039; =&gt; &#039;background-color: white;&#039;)
);

echo $view-&gt;contentPane(
    &#039;statusPane&#039;,
    &#039;Status area&#039;,
    array(&#039;region&#039; =&gt; &#039;bottom&#039;),
    array(&#039;style&#039; =&gt; &#039;background-color: lightgray;&#039;)
);

echo $view-&gt;borderContainer()-&gt;captureEnd(&#039;masterLayout&#039;);
</pre>

        </div>
    </div>

    <div class="section" id="zend.dojo.view.dijit.form"><div class="info"><h1 class="title">Dijit Form Elements</h1></div>
        

        <p class="para">
            Dojo&#039;s form validation and input dijits are in the <strong class="command">dijit.form</strong> tree.
            For more information on general usage of these elements, as well as
            accepted parameters, please <a href="http://dojotoolkit.org/reference-guide/dijit/form.html" class="link external">&raquo; visit
                the dijit.form documentation</a>.
        </p>

        <p class="para">
            The following dijit form elements are available in Zend Framework.
            Except where noted, all have the signature <strong class="command">string ($id,
                $value = &#039;&#039;, array $params = array(), array $attribs =
                array())</strong>.
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    <em class="emphasis">Button</em>: <strong class="command">dijit.form.Button</strong>. Display a
                    form button.
                </p>

                <pre class="programlisting brush: php">
&lt;?php echo $view-&gt;button(
    &#039;foo&#039;,
    &#039;Show Me!&#039;,
    array(&#039;iconClass&#039; =&gt; &#039;myButtons&#039;),
); ?&gt;
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">CheckBox</em>:
                    <strong class="command">dijit.form.CheckBox</strong>. Display a checkbox. Accepts an
                    optional fifth argument, the array
                    <var class="varname">$checkedOptions</var>, which may contain either:
                </p>

                <ul class="itemizedlist">
                    <li class="listitem">
                        <p class="para">
                            an indexed array with two values, a checked value
                            and unchecked value, in that order; or
                        </p>
                    </li>

                    <li class="listitem">
                        <p class="para">
                            an associative array with the keys &#039;checkedValue&#039;
                            and &#039;unCheckedValue&#039;.
                        </p>
                    </li>
                </ul>

                <p class="para">
                    If <var class="varname">$checkedOptions</var> is not provided, 1 and 0
                    are assumed.
                </p>

                <pre class="programlisting brush: php">
&lt;?php echo $view-&gt;checkBox(
    &#039;foo&#039;,
    &#039;bar&#039;,
    array(),
    array(),
    array(&#039;checkedValue&#039; =&gt; &#039;foo&#039;, &#039;unCheckedValue&#039; =&gt; &#039;bar&#039;)
); ?&gt;
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">ComboBox</em>:
                    <strong class="command">dijit.layout.ComboBox</strong>. ComboBoxes are a hybrid between a
                    select and a text box with autocompletion. The key
                    difference is that you may type an option that is not in
                    the list of available options, and it will still consider
                    it valid input. It accepts an optional fifth argument, an
                    associative array <var class="varname">$options</var>; if provided,
                    ComboBox will be rendered as a <em class="emphasis">select</em>. Note
                    also that the <em class="emphasis">label values</em> of the
                    <var class="varname">$options</var> array will be returned in the form --
                    not the values themselves.
                </p>

                <p class="para">
                    Alternately, you may pass information regarding a <strong class="command">dojo.data</strong>
                    datastore to use with the element. If provided, the
                    ComboBox will be rendered as a text <em class="emphasis">input</em>, and
                    will pull its options via that datastore.
                </p>

                <p class="para">
                    To specify a datastore, provide one of the following
                    <var class="varname">$params</var> key combinations:
                </p>

                <ul class="itemizedlist">
                    <li class="listitem">
                        <p class="para">
                            The key &#039;store&#039;, with an array value; the array
                            should contain the keys:
                        </p>

                        <ul class="itemizedlist">
                            <li class="listitem">
                                <p class="para">
                                    <em class="emphasis">store</em>: the name of the
                                    javascript variable representing the datastore
                                    (this could be the name you would like for it
                                    to use).
                                </p>
                            </li>

                            <li class="listitem">
                                <p class="para">
                                    <em class="emphasis">type</em>: the datastore type
                                    to use; e.g., &#039;<strong class="command">dojo.data.ItemFileReadStore</strong>&#039;.
                                </p>
                            </li>

                            <li class="listitem">
                                <p class="para">
                                    <em class="emphasis">params</em> (optional): an
                                    associative array of key and value pairs to use to
                                    configure the datastore. The &#039;url&#039; param is a
                                    typical example.
                                </p>
                            </li>
                        </ul>
                    </li>

                    <li class="listitem">
                        <p class="para">
                            The keys:
                        </p>

                        <ul class="itemizedlist">
                            <li class="listitem">
                                <p class="para">
                                    <em class="emphasis">store</em>: a string indicating
                                    the datastore name to use.
                                </p>
                            </li>

                            <li class="listitem">
                                <p class="para">
                                    <em class="emphasis">storeType</em>: a string indicating
                                    the datastore <strong class="command">dojo.data</strong> type to use (e.g.,
                                    &#039;<strong class="command">dojo.data.ItemFileReadStore</strong>&#039;).
                                </p>
                            </li>

                            <li class="listitem">
                                <p class="para">
                                    <em class="emphasis">storeParams</em>: an
                                    associative array of key and value pairs with which
                                    to configure the datastore.
                                </p>
                            </li>
                        </ul>
                    </li>
                </ul>

                <pre class="programlisting brush: php">
// As a select element:
echo $view-&gt;comboBox(
    &#039;foo&#039;,
    &#039;bar&#039;,
    array(
        &#039;autocomplete&#039; =&gt; false,
    ),
    array(),
    array(
        &#039;foo&#039; =&gt; &#039;Foo&#039;,
        &#039;bar&#039; =&gt; &#039;Bar&#039;,
        &#039;baz&#039; =&gt; &#039;Baz&#039;,
    )
);

// As a dojo.data-enabled element:
echo $view-&gt;comboBox(
    &#039;foo&#039;,
    &#039;bar&#039;,
    array(
        &#039;autocomplete&#039; =&gt; false,
        &#039;store&#039;        =&gt; &#039;stateStore&#039;,
        &#039;storeType&#039;    =&gt; &#039;dojo.data.ItemFileReadStore&#039;,
        &#039;storeParams&#039;  =&gt; array(&#039;url&#039; =&gt; &#039;/js/states.json&#039;),
    ),
);
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">CurrencyTextBox</em>:
                    <strong class="command">dijit.form.CurrencyTextBox</strong>. Inherits from
                    ValidationTextBox, and provides client-side validation of
                    currency. It expects that the dijit parameter &#039;currency&#039;
                    will be provided with an appropriate 3-character currency
                    code. You may also specify any dijit parameters valid for
                    ValidationTextBox and TextBox.
                </p>

                <pre class="programlisting brush: php">
echo $view-&gt;currencyTextBox(
    &#039;foo&#039;,
    &#039;$25.00&#039;,
    array(&#039;currency&#039; =&gt; &#039;USD&#039;),
    array(&#039;maxlength&#039; =&gt; 20)
);
</pre>


                <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Issues with Builds</b><br /></span>
                    

                    <p class="para">
                        There are currently <a href="http://trac.dojotoolkit.org/ticket/7183" class="link external">&raquo; known
                        issues with using CurrencyTextBox with build
                        layers</a>. A known work-around is to ensure that
                        your document&#039;s Content-Type http-equiv meta tag sets the
                        character set to utf-8, which you can do by calling:
                    </p>

                    <pre class="programlisting brush: php">
$view-&gt;headMeta()-&gt;appendHttpEquiv(&#039;Content-Type&#039;,
                                   &#039;text/html; charset=utf-8&#039;);
</pre>


                    <p class="para">
                        This will mean, of course, that you will need to ensure
                        that the  <span class="methodname">headMeta()</span> placeholder is echoed
                        in your layout script.
                    </p>
                </p></blockquote>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">DateTextBox</em>:
                    <strong class="command">dijit.form.DateTextBox</strong>. Inherits from
                    ValidationTextBox, and provides both client-side validation of
                    dates, as well as a dropdown calendar from which to select a date.
                    You may specify any dijit parameters available to
                    ValidationTextBox or TextBox.
                </p>

                <pre class="programlisting brush: php">
echo $view-&gt;dateTextBox(
    &#039;foo&#039;,
    &#039;2008-07-11&#039;,
    array(&#039;required&#039; =&gt; true)
);
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">Editor</em>: <strong class="command">dijit.Editor</strong>. Provides a
                    <acronym class="acronym">WYSIWYG</acronym> editor via which users may create or edit content.
                    <strong class="command">dijit.Editor</strong> is a pluggable, extensible editor
                    with a variety of parameters you can utilize for customization; see <a href="http://dojotoolkit.org/reference-guide/dijit/Editor.html" class="link external">&raquo; the
                        dijit.Editor documentation</a> for more details.
                </p>

                <pre class="programlisting brush: php">
echo $view-&gt;editor(&#039;foo&#039;);
</pre>


                <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Editor Dijit uses div by default</b><br /></span>
                    

                    <p class="para">
                        The Editor dijit uses an <acronym class="acronym">HTML</acronym> <acronym class="acronym">DIV</acronym> by
                        default. The <strong class="command">dijit._editor.RichText</strong> <a href="http://api.dojotoolkit.org/jsdoc/HEAD/dijit._editor.RichText" class="link external">&raquo; documentation</a>
                        indicates that having it built on an <acronym class="acronym">HTML</acronym>
                        <acronym class="acronym">TEXTAREA</acronym> can potentially have security implications.
                    </p>

                    <p class="para">
                        In order to allow graceful degradation in environments where Javascript is
                        unavailable, <span class="classname">Zend_Dojo_View_Helper_Editor</span> also wraps
                        a <acronym class="acronym">TEXTAREA</acronym> within a <acronym class="acronym">NOSCRIPT</acronym> tag;
                        the content of this <acronym class="acronym">TEXTAREA</acronym> will be properly escaped to
                        avoid security vulnerability vectors.
                    </p>
                </p></blockquote>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">FilteringSelect</em>:
                    <strong class="command">dijit.form.FilteringSelect</strong>. Similar to ComboBox, this is a
                    select and text hybrid that can either render a provided list
                    of options or those fetched via a <strong class="command">dojo.data</strong> datastore.
                    Unlike ComboBox, however, FilteringSelect does not allow
                    typing in an option not in its list. Additionally, it
                    operates like a standard select in that the option values,
                    not the labels, are returned when the form is submitted.
                </p>

                <p class="para">
                    Please see the information above on ComboBox for examples
                    and available options for defining datastores.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">HorizontalSlider</em> and
                    <em class="emphasis">VerticalSlider</em>:
                    <strong class="command">dijit.form.HorizontalSlider</strong> and
                    <strong class="command">dijit.form.VerticalSlider</strong>. Sliders allow are UI widgets for
                    selecting numbers in a given range; these are horizontal and vertical variants.
                </p>

                <p class="para">
                    At their most basic, they require the dijit parameters
                    &#039;minimum&#039;, &#039;maximum&#039;, and &#039;discreteValues&#039;. These define
                    the range of values. Other common options are:
                </p>

                <ul class="itemizedlist">
                    <li class="listitem">
                        <p class="para">
                            &#039;intermediateChanges&#039; can be set to indicate whether or not
                            to fire onChange events while the handle is being dragged.
                        </p>
                    </li>

                    <li class="listitem">
                        <p class="para">
                            &#039;clickSelect&#039; can be set to allow clicking a location
                            on the slider to set the value.
                        </p>
                    </li>

                    <li class="listitem">
                        <p class="para">
                            &#039;pageIncrement&#039; can specify the value by which to
                            increase or decrease when pageUp and pageDown are used.
                        </p>
                    </li>

                    <li class="listitem">
                        <p class="para">
                            &#039;showButtons&#039; can be set to allow displaying buttons on
                            either end of the slider for manipulating the value.
                        </p>
                    </li>
                </ul>

                <p class="para">
                    The implication from Zend Framework creates a hidden element
                    to store the value of the slider.
                </p>

                <p class="para">
                    You may optionally desire to show a rule or labels for the
                    slider. To do so, you will assign one or more of the dijit
                    params &#039;topDecoration&#039; and/or &#039;bottomDecoration&#039;
                    (HorizontalSlider) or &#039;leftDecoration&#039; and/or
                    &#039;rightDecoration&#039; (VerticalSlider). Each of these expects
                    the following options:
                </p>

                <ul class="itemizedlist">
                    <li class="listitem">
                        <p class="para">
                            <em class="emphasis">container</em>: name of the container.
                        </p>
                    </li>

                    <li class="listitem">
                        <p class="para">
                            <em class="emphasis">labels</em> (optional): an array of
                            labels to utilize. Use empty strings on either end to
                            provide labels for inner values only. Required when
                            specifying one of the &#039;Labels&#039; dijit variants.
                        </p>
                    </li>

                    <li class="listitem">
                        <p class="para">
                            <em class="emphasis">dijit</em> (optional): one of
                            HorizontalRule, HorizontalRuleLabels, VerticalRule, or
                            VerticalRuleLabels, Defaults to one of the Rule dijits.
                        </p>
                    </li>

                    <li class="listitem">
                        <p class="para">
                            <em class="emphasis">params</em> (optional): dijit params
                            for configuring the Rule dijit in use. Parameters
                            specific to these dijits include:
                        </p>

                        <ul class="itemizedlist">
                            <li class="listitem">
                                <p class="para">
                                    <em class="emphasis">container</em> (optional):
                                    array of parameters and attributes for the rule
                                    container.
                                </p>
                            </li>

                            <li class="listitem">
                                <p class="para">
                                    <em class="emphasis">labels</em> (optional):
                                    array of parameters and attributes for the
                                    labels list container.
                                </p>
                            </li>
                        </ul>
                    </li>

                    <li class="listitem">
                        <p class="para">
                            <em class="emphasis">attribs</em> (optional): <acronym class="acronym">HTML</acronym>
                            attributes to use with the rules and labels. This should
                            follow the <span class="property">params</span> option format and be an
                            associative array with the keys &#039;container&#039; and
                            &#039;labels&#039;.
                        </p>
                    </li>
                </ul>

                <pre class="programlisting brush: php">
echo $view-&gt;horizontalSlider(
    &#039;foo&#039;,
    1,
    array(
        &#039;minimum&#039;             =&gt; -10,
        &#039;maximum&#039;             =&gt; 10,
        &#039;discreteValues&#039;      =&gt; 11,
        &#039;intermediateChanges&#039; =&gt; true,
        &#039;showButtons&#039;         =&gt; true,
        &#039;topDecoration&#039;       =&gt; array(
            &#039;container&#039; =&gt; &#039;topContainer&#039;
            &#039;dijit&#039;     =&gt; &#039;HorizontalRuleLabels&#039;,
            &#039;labels&#039;    =&gt; array(
                &#039; &#039;,
                &#039;20%&#039;,
                &#039;40%&#039;,
                &#039;60%&#039;,
                &#039;80%&#039;,
                &#039; &#039;,
            ),
            &#039;params&#039; =&gt; array(
                &#039;container&#039; =&gt; array(
                    &#039;style&#039; =&gt; &#039;height:1.2em; font-size=75%;color:gray;&#039;,
                ),
                &#039;labels&#039; =&gt; array(
                    &#039;style&#039; =&gt; &#039;height:1em; font-size=75%;color:gray;&#039;,
                ),
            ),
        ),
        &#039;bottomDecoration&#039;    =&gt; array(
            &#039;container&#039; =&gt; &#039;bottomContainer&#039;
            &#039;labels&#039;    =&gt; array(
                &#039;0%&#039;,
                &#039;50%&#039;,
                &#039;100%&#039;,
            ),
            &#039;params&#039; =&gt; array(
                &#039;container&#039; =&gt; array(
                    &#039;style&#039; =&gt; &#039;height:1.2em; font-size=75%;color:gray;&#039;,
                ),
                &#039;labels&#039; =&gt; array(
                    &#039;style&#039; =&gt; &#039;height:1em; font-size=75%;color:gray;&#039;,
                ),
            ),
        ),
    )
);
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">NumberSpinner</em>:
                    <strong class="command">dijit.form.NumberSpinner</strong>. Text box for numeric entry, with
                    buttons for incrementing and decrementing.
                </p>

                <p class="para">
                    Expects either an associative array for the dijit parameter
                    &#039;constraints&#039;, or simply the keys &#039;min&#039;, &#039;max&#039;, and
                    &#039;places&#039; (these would be the expected entries of the
                    constraints parameter as well). &#039;places&#039; can be used to
                    indicate how much the number spinner will increment and
                    decrement.
                </p>

                <pre class="programlisting brush: php">
echo $view-&gt;numberSpinner(
    &#039;foo&#039;,
    5,
    array(
        &#039;min&#039;    =&gt; -10,
        &#039;max&#039;    =&gt; 10,
        &#039;places&#039; =&gt; 2,
    ),
    array(
        &#039;maxlenth&#039; =&gt; 3,
    )
);
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">NumberTextBox</em>:
                    <strong class="command">dijit.form.NumberTextBox</strong>. NumberTextBox provides the
                    ability to format and display number entries in a localized
                    fashion, as well as validate numerical entries, optionally
                    against given constraints.
                </p>

                <pre class="programlisting brush: php">
echo $view-&gt;numberTextBox(
    &#039;foo&#039;,
    5,
    array(
        &#039;places&#039; =&gt; 4,
        &#039;type&#039;   =&gt; &#039;percent&#039;,
    ),
    array(
        &#039;maxlength&#039; =&gt; 20,
    )
);
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">PasswordTextBox</em>:
                    <strong class="command">dijit.form.ValidationTextBox</strong> tied to a password input.
                    PasswordTextBox provides the
                    ability to create password input that adheres to the current
                    dijit theme, as well as allow for client-side validation.
                </p>

                <pre class="programlisting brush: php">
echo $view-&gt;passwordTextBox(
    &#039;foo&#039;,
    &#039;&#039;,
    array(
        &#039;required&#039; =&gt; true,
    ),
    array(
        &#039;maxlength&#039; =&gt; 20,
    )
);
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">RadioButton</em>: <strong class="command">dijit.form.RadioButton</strong>. A
                    set of options from which only one may be selected. This
                    behaves in every way like a regular radio, but has a
                    look-and-feel consistent with other dijits.
                </p>

                <p class="para">
                    RadioButton accepts an optional fifth argument,
                    <var class="varname">$options</var>, an associative array of value and label
                    pairs used as the radio options. You may also pass these as
                    the <var class="varname">$attribs</var> key <span class="property">options</span>.
                </p>

                <pre class="programlisting brush: php">
echo $view-&gt;radioButton(
    &#039;foo&#039;,
    &#039;bar&#039;,
    array(),
    array(),
    array(
        &#039;foo&#039; =&gt; &#039;Foo&#039;,
        &#039;bar&#039; =&gt; &#039;Bar&#039;,
        &#039;baz&#039; =&gt; &#039;Baz&#039;,
    )
);
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">SimpleTextarea</em>:
                    <strong class="command">dijit.form.SimpleTextarea</strong>. These act like normal textareas,
                    but are styled using the current dijit theme. You do not need to specify either
                    the rows or columns attributes; use <span class="property">ems</span> or
                    percentages for the width and height, instead.
                </p>

                <pre class="programlisting brush: php">
echo $view-&gt;simpleTextarea(
    &#039;foo&#039;,
    &#039;Start writing here...&#039;,
    array(),
    array(&#039;style&#039; =&gt; &#039;width: 90%; height: 5ems;&#039;)
);
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">SubmitButton</em>: a <strong class="command">dijit.form.Button</strong> tied
                    to a submit input element. See the Button view helper for
                    more details; the key difference is that this button can
                    submit a form.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">Textarea</em>: <strong class="command">dijit.form.Textarea</strong>. These
                    act like normal textareas, except that instead of having a
                    set number of rows, they expand as the user types. The
                    width should be specified via a style setting.
                </p>

                <pre class="programlisting brush: php">
echo $view-&gt;textarea(
    &#039;foo&#039;,
    &#039;Start writing here...&#039;,
    array(),
    array(&#039;style&#039; =&gt; &#039;width: 300px;&#039;)
);
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">TextBox</em>: <strong class="command">dijit.form.TextBox</strong>. This
                    element is primarily present to provide a common
                    look-and-feel between various dijit elements, and to
                    provide base functionality for the other TextBox-derived
                    classes (ValidationTextBox, NumberTextBox, CurrencyTextBox,
                    DateTextBox, and TimeTextBox).
                </p>

                <p class="para">
                    Common dijit parameter flags include &#039;lowercase&#039; (cast to
                    lowercase), &#039;uppercase&#039; (cast to <acronym class="acronym">UPPERCASE</acronym>), &#039;propercase&#039;
                    (cast to Proper Case), and trim (trim leading and trailing
                    whitespace); all accept boolean values. Additionally, you
                    may specifiy the parameters &#039;size&#039; and &#039;maxLength&#039;.
                </p>

                <pre class="programlisting brush: php">
echo $view-&gt;textBox(
    &#039;foo&#039;,
    &#039;some text&#039;,
    array(
        &#039;trim&#039;       =&gt; true,
        &#039;propercase&#039; =&gt; true,
        &#039;maxLength&#039;  =&gt; 20,
    ),
    array(
        &#039;size&#039; =&gt; 20,
    )
);
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">TimeTextBox</em>: <strong class="command">dijit.form.TimeTextBox</strong>.
                    Also in the TextBox family, TimeTextBox provides a
                    scrollable drop down selection of times from which a user
                    may select. Dijit parameters allow you to specify the time
                    increments available in the select as well as the visible
                    range of times available.
                </p>

                <pre class="programlisting brush: php">
echo $view-&gt;timeTextBox(
    &#039;foo&#039;,
    &#039;&#039;,
    array(
        &#039;am.pm&#039;            =&gt; true,
        &#039;visibleIncrement&#039; =&gt; &#039;T00:05:00&#039;, // 5-minute increments
        &#039;visibleRange&#039;     =&gt; &#039;T02:00:00&#039;, // show 2 hours of increments
    ),
    array(
        &#039;size&#039; =&gt; 20,
    )
);
</pre>

            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">ValidationTextBox</em>:
                    <strong class="command">dijit.form.ValidateTextBox</strong>. Provide client-side validations
                    for a text element. Inherits from TextBox.
                </p>

                <p class="para">
                    Common dijit parameters include:
                </p>

                <ul class="itemizedlist">
                    <li class="listitem">
                        <p class="para">
                            <em class="emphasis">invalidMessage</em>: a message to
                            display when an invalid entry is detected.
                        </p>
                    </li>

                    <li class="listitem">
                        <p class="para">
                            <em class="emphasis">promptMessage</em>: a tooltip help
                            message to use.
                        </p>
                    </li>

                    <li class="listitem">
                        <p class="para">
                            <em class="emphasis">regExp</em>: a regular expression to
                            use to validate the text. Regular expression does not
                            require boundary markers.
                        </p>
                    </li>

                    <li class="listitem">
                        <p class="para">
                            <em class="emphasis">required</em>: whether or not the
                            element is required. If so, and the element is embedded
                            in a <strong class="command">dijit.form.Form</strong>, it will be flagged as invalid
                            and prevent submission.
                        </p>
                    </li>
                </ul>

                <pre class="programlisting brush: php">
echo $view-&gt;validationTextBox(
    &#039;foo&#039;,
    &#039;&#039;,
    array(
        &#039;required&#039; =&gt; true,
        &#039;regExp&#039;   =&gt; &#039;[\w]+&#039;,
        &#039;invalidMessage&#039; =&gt; &#039;No spaces or non-word characters allowed&#039;,
        &#039;promptMessage&#039;  =&gt; &#039;Single word consisting of alphanumeric &#039; .
                            &#039;characters and underscores only&#039;,
    ),
    array(
        &#039;maxlength&#039; =&gt; 20,
    )
);
</pre>

            </li>
        </ul>
    </div>

    <div class="section" id="zend.dojo.view.dijit.custom"><div class="info"><h1 class="title">Custom Dijits</h1></div>
        

        <p class="para">
            If you delve into Dojo much at all, you&#039;ll find yourself writing
            custom dijits, or using experimental dijits from Dojox. While Zend
            Framework cannot support every dijit directly, it does provide some
            rudimentary support for arbitrary dijit types via the
            <span class="classname">CustomDijit</span> view helper.
        </p>

        <p class="para">
            The <span class="classname">CustomDijit</span> view helper&#039;s <acronym class="acronym">API</acronym> is exactly
            that of any other dijit, with one major difference: the third &quot;params&quot;
            argument <em class="emphasis">must</em> contain the attribute &quot;dojotype&quot;.
            The value of this attribute should be the Dijit class you plan to
            use.
        </p>

        <p class="para">
            <span class="classname">CustomDijit</span> extends the base
            <span class="classname">DijitContainer</span> view helper, which also allows it to
            capture content (using the
             <span class="methodname">captureStart()</span>/ <span class="methodname">captureEnd()</span> pair of
            methods).  <span class="methodname">captureStart()</span> also expects that you pass the
            &quot;dojoType&quot; attribute to its &quot;params&quot; argument.
        </p>

        <div class="example" id="zend.dojo.view.dijit.custom.example"><div class="info"><p><b>Example #6 Using CustomDijit to render a dojox.layout.ContentPane</b></p></div>
            

            <div class="example-contents"><p>
                <strong class="command">dojox.layout.ContentPane</strong> is a next-generation
                iteration of <strong class="command">dijit.layout.ContentPane</strong>, and provides
                a superset of that class&#039;s capabilities. Until it&#039;s
                functionality stabilizes, it will continue to live in Dojox.
                However, if you want to use it in Zend Framework today, you can,
                using the <span class="classname">CustomDijit</span> view helper.
            </p></div>

            <div class="example-contents"><p>
                At its most basic, you can do the following:
            </p></div>

            <pre class="programlisting brush: php">
&lt;?php echo $this-&gt;customDijit(
    &#039;foo&#039;,
    $content,
    array(
        &#039;dojoType&#039; =&gt; &#039;dojox.layout.ContentPane&#039;,
        &#039;title&#039;    =&gt; &#039;Custom pane&#039;,
        &#039;region&#039;   =&gt; &#039;center&#039;
    )
); ?&gt;
</pre>


            <div class="example-contents"><p>
                If you wanted to capture content instead, simply use the
                 <span class="methodname">captureStart()</span> method, and pass the &quot;dojoType&quot; to
                the &quot;params&quot; argument:
            </p></div>

            <pre class="programlisting brush: php">
&lt;?php $this-&gt;customDijit()-&gt;captureStart(
    &#039;foo&#039;,
    array(
        &#039;dojoType&#039; =&gt; &#039;dojox.layout.ContentPane&#039;,
        &#039;title&#039;    =&gt; &#039;Custom pane&#039;,
        &#039;region&#039;   =&gt; &#039;center&#039;
    )
); ?&gt;
This is the content of the pane
&lt;?php echo $this-&gt;customDijit()-&gt;captureEnd(&#039;foo&#039;); ?&gt;
</pre>


            <div class="example-contents"><p>
                You can also extend <span class="classname">CustomDijit</span> easily to create
                support for your own custom dijits. As an example, if you
                extended <strong class="command">dijit.layout.ContentPane</strong> to create your
                own <strong class="command">foo.ContentPane</strong> class, you could create the
                following helper to support it:
            </p></div>

            <pre class="programlisting brush: php">
class My_View_Helper_FooContentPane
    extends Zend_Dojo_View_Helper_CustomDijit
{
    protected $_defaultDojoType = &#039;foo.ContentPane&#039;;

    public function fooContentPane(
        $id = null, $value = null,
        array $params = array(), array $attribs = array()
    ) {
        return $this-&gt;customDijit($id, $value, $params, $attribs);
    }
}
</pre>


            <div class="example-contents"><p>
                As long as your custom dijit follows the same basic <acronym class="acronym">API</acronym> as
                official dijits, using or extending <span class="classname">CustomDijit</span>
                should work correctly.
            </p></div>
        </div>
    </div>
</div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.dojo.data.html">Zend_Dojo_Data: dojo.data Envelopes</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.dojo.html">Zend_Dojo</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.dojo.form.html">Dojo Form Elements and Decorators</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="reference.html">Refer&ecirc;ncia do Zend Framework</a></li>
  <li class="header up"><a href="zend.dojo.html">Zend_Dojo</a></li>
  <li><a href="zend.dojo.introduction.html">Introduction</a></li>
  <li><a href="zend.dojo.data.html">Zend_Dojo_Data: dojo.data Envelopes</a></li>
  <li class="active"><a href="zend.dojo.view.html">Dojo View Helpers</a></li>
  <li><a href="zend.dojo.form.html">Dojo Form Elements and Decorators</a></li>
  <li><a href="zend.dojo.build-layers.html">Zend_Dojo build layer support</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>